home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Tools 4
/
Amiga Tools 4.iso
/
tools
/
wb-enhancement
/
swazblanker
/
programmer
/
autodoc
/
matrix.doc
next >
Wrap
Text File
|
1996-02-26
|
73KB
|
2,886 lines
TABLE OF CONTENTS
matrix.library/--Event_FontGadgetNew--
matrix.library/--MX_FormatMXSB--
matrix.library/--MX_ScreenButton_Remake--
matrix.library/--background--
matrix.library/MX_AddArexxPort
matrix.library/MX_AddNodeSorted
matrix.library/MX_AddVBlankNode
matrix.library/MX_AllocMem
matrix.library/MX_AllocVecStr
matrix.library/MX_CDToAssigns
matrix.library/MX_CPUName
matrix.library/MX_CleanUpGList
matrix.library/MX_CloneListByName
matrix.library/MX_CloseForm
matrix.library/MX_CloseWinSafe
matrix.library/MX_CompressInfo
matrix.library/MX_CompressTrue
matrix.library/MX_CurrentTime
matrix.library/MX_DeCompress
matrix.library/MX_DeCompressTrue
matrix.library/MX_DeleteDirectory
matrix.library/MX_DisplayRequest
matrix.library/MX_DisplayRequestWin
matrix.library/MX_DosOpen
matrix.library/MX_ExamineDir
matrix.library/MX_Free8SVX
matrix.library/MX_FreeArgs
matrix.library/MX_FreeFIB
matrix.library/MX_FreeFont
matrix.library/MX_FreeList
matrix.library/MX_FreeListNodes
matrix.library/MX_FreeMem
matrix.library/MX_FullWBArgName
matrix.library/MX_GetCatalogStr
matrix.library/MX_GetFont
matrix.library/MX_HexStrLong
matrix.library/MX_HookTag
matrix.library/MX_HookTagOrdered
matrix.library/MX_JustifyText
matrix.library/MX_ListToArray
matrix.library/MX_Load8SVX
matrix.library/MX_LoadFIB
matrix.library/MX_LoadFile
matrix.library/MX_LoadIFF
matrix.library/MX_LockMxBase
matrix.library/MX_MakeMenu_Localize
matrix.library/MX_MakePath
matrix.library/MX_ModifyListview
matrix.library/MX_NewLoadIFF
matrix.library/MX_NewPrefsWH
matrix.library/MX_NewReadArgs
matrix.library/MX_NewSaveIFF
matrix.library/MX_NewSortList
matrix.library/MX_NextForm
matrix.library/MX_OpenForm
matrix.library/MX_OpenFormReq
matrix.library/MX_OpenPathNew
matrix.library/MX_PatternMatch
matrix.library/MX_ProcessArexxPort
matrix.library/MX_QuickSort
matrix.library/MX_Random
matrix.library/MX_RandomInRange
matrix.library/MX_RandomSeed
matrix.library/MX_RawFormat
matrix.library/MX_ReadArgs
matrix.library/MX_ReadForm
matrix.library/MX_ReadFormTagList
matrix.library/MX_RemArexxPort
matrix.library/MX_RemVBlankNode
matrix.library/MX_RemakeGadgets
matrix.library/MX_ReplaceTags
matrix.library/MX_ReplaceVecStr
matrix.library/MX_SaveIFF
matrix.library/MX_SeekForm
matrix.library/MX_SelectGadget
matrix.library/MX_SendArexxString
matrix.library/MX_SetListView
matrix.library/MX_SetWaitPointer
matrix.library/MX_ShowWindow
matrix.library/MX_SortList
matrix.library/MX_SoundID
matrix.library/MX_StrCpyLen
matrix.library/MX_StrCpyWord
matrix.library/MX_StrLen
matrix.library/MX_TaskName
matrix.library/MX_TextFileToList
matrix.library/MX_TimeString
matrix.library/MX_UnlockMxBase
matrix.library/MX_UnlockWindow
matrix.library/MX_UpdateVBLankInterrupt
matrix.library/MX_WhereAmI
matrix.library/MX_WindowHandler
matrix.library/MX_WrapText
matrix.library/MX_WriteForm
matrix.library/MX_WriteFormTagList
matrix.library/--Event_FontGadgetNew-- matrix.library/--Event_FontGadgetNew--
PURPOSE
This function is private.
SYNTAX
Event_FontGadgetNew(gadget,IMsg,whStruct)
a1 a4 a5
SEE ALSO
MX_WindowHandler(), MX_CreateGadgets().
matrix.library/--MX_FormatMXSB-- matrix.library/--MX_FormatMXSB--
PURPOSE
This function is private.
Formats the text used by screen mode gadgets.
SYNTAX
MX_FormatMXSB(mxScreenButtonData,mxBase)
a0 a6
struct MxScreenModeButton *mxScreenButtonData;
INPUTS
mxScreenButtonData = pointer to data field made by
MX_CreateGadgets() to track information. This
can be obtained from the gadgets userdata field.
RESULT
None.
SEE ALSO
MX_WindowHandler(), MX_CreateGadgets().
matrix.library/--MX_ScreenButton_Remake-- matrix.library/--MX_ScreenButton_Remake--
PURPOSE
This function is private.
Refreshes the screenmode gadget.
SYNTAX
MX_ScreenButton_Remake(gad,win,mxBase)
a0 a1 a6
struct Gadget *gad;
struct Window *win;
INPUTS
gad = pointer to a mxScreenMode gadget made by
MX_CreateGadgets(). This will be refreshed to
reflect any changes made in its data storage
area.
win = pointer to window containing gadget.
RESULT
None.
SEE ALSO
MX_WindowHandler(), MX_CreateGadgets().
matrix.library/--background-- matrix.library/--background--
PURPOSE
Unknown.
OVERVIEW
All information contained in this document is
confidentional and may not be distributed.
matrix.library/MX_AddArexxPort matrix.library/MX_AddArexxPort
NAME
MX_AddArexxPort -- add a public arexx message port. (V23)
SYNOPSIS
port = MX_AddArexxPort(name,hook,[userdata])
d0 a0 a1 [d0]
struct MsgPort *port;
STRPTR name;
APTR hook;
LONG userdata;
FUNCTION
Add an arexx port to the system public port list safely.
INPUTS
name - pointer to name of the public port. This name is copied into
public memory using MX_AllocVecStr(). It is therefore necessary
to call MX_RemArexxPort() when removing the arexx port so that
this memory may also be deallocated.
hook - pointer to user function that is called when a port is found
with the same name as the one we wish to create. The hook is
invoked as follows:
result = userhook(port,userdata)
d0 a0 a0
RESULT
port = pointer to created message port or NULL if a port with the
same name has been found (the user hook would have been invoked)
or we are unable to allocate sufficient memory.
NOTES
The userhook callback is called within a Forbid() permit so that the
port is unable to go away, unless the task goes into a Wait().
Also the result return value should always return NULL. This may be
used at a later stage for a retry/cancel mode.
SEE ALSO
MX_RemArexxPort(), MX_ProcessArexxPort(), MX_AllocVecStr(),
exec.library/FindPort(), exec.library/CreateMsgPort(),
exec.library/AddPort(), exec.library/Forbid(), exec.library/Permit(),
exec.library/Wait().
matrix.library/MX_AddNodeSorted matrix.library/MX_AddNodeSorted
NAME
MX_AddNodeSorted -- add node to linked list (V22)
SYNOPSIS
pos = MX_AddNodeSorted(list,node)
d0 a0 a1
ULONG pos;
APTR list;
APTR node;
FUNCTION
Add a node into a linked list into prioritized alphbetic order.
INPUTS
pos = position added into list
list = pointer to initialized list head.
node = node to add into the list in prioritized alphabetic order.
Make sure the LN_PRI and LN_NAME fields are set.
RESULT
None
NOTES
Make sure the LN_PRI field of each node is set, if you do
not want a prioritized sort then set this to zero for all nodes.
SEE ALSO
MX_SortList()
matrix.library/MX_AddVBlankNode matrix.library/MX_AddVBlankNode
NAME
MX_AddVBlankNode -- add vblank server hook or signal (V23)
SYNOPSIS
vbn = MX_AddVBlankNode(tags)
d0 a0
struct MXVBlankNode *vbn;
struct TagItem *tags;
FUNCTION
Add hook or signal to the matrix vblank interrupt server.
INPUTS
tags = pointer to a tagitem array.
RESULT
vbn = pointer to allocated vblank node or NULL if failed.
TAGS
MXVB_HookAddress (APTR) - set a hook routine to call when a
vertical blank occurs. The hook is called as follows:
userhook(vbn,userdata)(a0,d0)
This tag is mutually exclusive to MXVB_SigBit.
MXVB_UserData (ULONG) - user definable field passed to hook
function.
MXVB_SigBit (UBYTE) - this will be the signal bit to signal the
task that is adding the vblank node. This tag is mutually
exclusive to MXVB_HookAddress.
MXVB_Count (BYTE) - number of vertical blanks that are to occur
before the hook address of signal is called.
SEE ALSO
MX_RemVBlankNode(), MX_UpdateVBLankInterrupt()
matrix.library/MX_AllocMem matrix.library/MX_AllocMem
NAME
MX_AllocMem -- OBSOLETE FUNCTION
SYNOPSIS
mem = MX_AllocMem(size)
d0 d0
matrix.library/MX_AllocVecStr matrix.library/MX_AllocVecStr
NAME
MX_AllocVecStr -- alloc a string and buffer (V23)
SYNOPSIS
mem = MX_AllocVecStr(string,attributes)
d0 a0 d1
APTR mem;
STRPTR string;
ULONG attributes;
FUNCTION
Allocates a buffer for the string and copys the string into
the buffer.
INPUTS
string = pointer to a string.
attributes = exec.library/AllocVec() memory attributes.
RESULT
Pointer to buffer containing the string, or NULL if not enough
memory for the buffer.
NOTE
Use exec.library/FreeVec() to deallocate the buffer.
SEE ALSO
MX_ReplaceVecStr(), exec.library/AllocVec(), exec.library/FreeVec()
matrix.library/MX_CDToAssigns matrix.library/MX_CDToAssigns
NAME
MX_CDToAssigns -- change directory to all assigns
SYNOPSIS
success = MX_CDToAssigns(name,hook,[userdata])
d0 a0 a1 [d0]
BOOLEAN success;
STRPTR name;
APTR hook;
ULONG userdata;
INPUTS
name =
hook =
userdata =
RESULT
TRUE if successful
SEE ALSO
matrix.library/MX_CPUName matrix.library/MX_CPUName
NAME
MX_CPUName -- get the type of CPU
SYNOPSIS
name = MX_CPUName(attnflag,tags)
a0 d0 d1
INPUTS
attnflag = as per execbase
tags = none defined. Leave this as NULL
RESULT
name = pointer to description of CPU
NOTES
Please not that a2 *IS* trashed
a1 = *FPUName
a2 = *MMUName
matrix.library/MX_CleanUpGList matrix.library/MX_CleanUpGList
NAME
MX_CleanUpGList -- Dispose of the gadgets
SYNOPSIS
MX_CleanUpGList(firstGadget,Number)
d0 d1
struct Gadget *firstGadget;
ULONG Number;
FUNCTION
Deallocates structures allocated for the gadgets set
up by MX_CreateGadgets()
INPUTS
firstGadget = pointer to first gadget. NULL does nothing.
Number = number of gadgets to cleanup.
RESULT
None
SEE ALSO
MX_CreateGadgets(), MX_RemakeGadgets()
matrix.library/MX_CloneListByName matrix.library/MX_CloneListByName
NAME
matrix.library/MX_CloneListByName -- Duplicate a list by name only.
SYNOPSIS
list = MX_CloneListByName(sourcelist,function,tags)
d0 a0 a1 a2
STRUCT list *list;
STRUCT list *sourcelist;
APTR function;
struct TagItem *tags;
FUNCTION
Creates a list based upon the source list. If no user function
is provided the created list is a duplicate list of the node names
of the source list only. If the user function is provided then
the created list is a list of the names returned by the function.
INPUTS
list - pointer to source list.
function - pointer to user function or NULL. The user function
fills a buffer with the required node name based upon the source
node. The user function is called as:
result = Function(buffer,node)
d0 a0 a1
If the result returned is FALSE then the buffer will not be
added to the list.
tags - none available.
RESULT
list - pointer to list, use MX_FreeList() to deallocate.
TAGS
None available.
NOTES
The buffer is currently only 200 bytes long. Tags may be provided
later to change this.
SEE ALSO
MX_FreeList()
matrix.library/MX_CloseForm matrix.library/MX_CloseForm
NAME
MX_CloseForm -- OBSOLETE FUNCTION
SYNOPSIS
MX_CloseForm(formhandle)
d0
matrix.library/MX_CloseWinSafe matrix.library/MX_CloseWinSafe
NAME
MX_CloseWinSafe -- close a window with a shared IDCMP port. (V22)
SYNOPSIS
MX_CloseWinSafe(window)
a0
struct Window *window;
FUNCTION
Detaches the IDCMP port from a window before closing and removes
and replies any outstanding messages.
INPUTS
window = pointer to window to close.
RESULT
None.
SEE ALSO
intuition.library/CloseWindow()
matrix.library/MX_CompressInfo matrix.library/MX_CompressInfo
NAME
MX_CompressInfo -- query buffer compression (V24)
SYNOPSIS
buffer, length = MX_CompressInfo(srcData)
a0 d0 a0
APTR buffer
ULONG length
APTR srcData
FUNCTION
How long is the decompressed buffer.
INPUTS
srcData = Pointer to compressed data stream
RESULT
The length of the decompressed buffer. Returns ZERO if the buffer
is not a matrix compression buffer.
Also returns pointer to start of compressed data in a0.
NOTES
SEE ALSO
MX_CompressTrue(), MX_CompressText(), MX_DeCompress(),
MX_DeCompressTableSize().
matrix.library/MX_CompressTrue matrix.library/MX_CompressTrue
NAME
MX_CompressTrue -- compress a buffer (V24)
SYNOPSIS
buffer,length = MX_CompressTrue(srcData,srcLen)
d0 d1 a0 d0
APTR buffer
ULONG length
APTR srcData
ULONG srcLen
FUNCTION
Compress a buffer.
INPUTS
srcData = Pointer to sorce buffer
srcLen = length of source data
RESULT
Pointer to compressed buffer. This should be freed using
exec.library/FreeVec(). This buffer can be decompressed
using MX_DeCompressTrue(). The length of the buffer is
returned in d1. The length of the buffer when decompressed
may be obtained from the buffer header which is as
follows:
STRUTURE MXCompressHeader,4 ; 4 byte identifier
ULONG mxcp_Len
LABEL mxcp_SIZE
NOTES
SEE ALSO
MX_DeCompressTrue()
matrix.library/MX_CurrentTime matrix.library/MX_CurrentTime
NAME
MX_CurrentTime() -- get the current time in seconds (V20)
SYNOPSIS
seconds = MX_CurrentTime()
d0
FUNCTION
Returns the current time in seconds.
INPUTS
None
RESULT
seconds - number of seconds elapsed since 01-Jan-1978.
NOTE
The number of microseconds is returned in d1.
SEE ALSO
intuition.library/CurrentTime(), timer.device/TR_GETSYSTIME
matrix.library/MX_DeCompress matrix.library/MX_DeCompress
NAME
MX_DeCompress -- decompress a compressed buffer (V24)
SYNOPSIS
result = MX_DeCompress(srcData,destData,table)
a0 a0 a1 a2
APTR srcData
APTR destData
APTR table
APTR result
FUNCTION
Decompress data compressed with MX_Compress()
INPUTS
srcData = Pointer to compressed source stream
destData = Pointer to destination data
table = Pointer to an area for the hash tables, of size found with
MX_DecompessTableSize().
RESULT
Pointer to end of compressed data.
NOTES
SEE ALSO
MX_Compress(), MX_DeCompress()
matrix.library/MX_DeCompressTrue matrix.library/MX_DeCompressTrue
NAME
MX_DeCompressTrue -- decompress a buffer (V24)
SYNOPSIS
buffer, length = MX_DeCompressTrue(srcData)
d0 d1 a0
APTR buffer
ULONG length
APTR srcData
FUNCTION
Decompress a buffer compressed with MX_CompressText()
or MX_CompressTrue().
INPUTS
srcData = Pointer to compressed data stream
RESULT
Pointer to decompressed buffer. This should be freed using
exec.library/FreeVec().
NOTES
SEE ALSO
MX_CompressTrue(), MX_CompressText(), MX_DeCompress(),
MX_DeCompressTableSize().
matrix.library/MX_DeleteDirectory matrix.library/MX_DeleteDirectory
NAME
MX_DeleteDirectory -- delete a diretory and its contents. (V22)
SYNOPSIS
success = MX_DeleteDirectory(name,tags)
d0 a0 d0
BOOL success;
STRPTR name;
struct TagList *tags;
FUNCTON
Deletes a directory and all subdirectories and files.
INPUTS
name = pointer to directory path.
tags = pointer to a taglist. None are supported.
RESULT
success = TRUE if successful, FALSE otherwise.
SEE ALSO
dos.library/DeleteFile(), MX_MakePath()
matrix.library/MX_DisplayRequest matrix.library/MX_DisplayRequest
NAME
MX_DisplayRequest -- display a request to the user (V23)
SYNOPSIS
result = MX_DisplayRequest(body,buttons,data)
d0 a0 a1 a2
ULONG result;
STRPTR body;
STRPTR buttons;
APTR data;
FUNCTON
Displays a request to the user either by an intuition
requestor or with output to cli, depending on where the
task was run from.
INPUTS
body = pointer to format string for the body text. If
NULL then this function performs no action.
buttons = pointer to format string for the buttons
data = data for the formatting strings
RESULT
0, 1, ..., N = Successive GadgetID values, for the gadgets
you specify for the requester. NOTE: The numbering
from left to right is actually: 1, 2, ..., N, 0.
NOTES
Currently under V23 when run from the CLI this function
only displays the body text and will return 0.
SEE ALSO
MX_DisplayRequestWin(), exec.library/RawDoFmt(),
intuition.library/EasyRequestArgs() dos.library/VPrintf()
matrix.library/MX_DisplayRequestWin matrix.library/MX_DisplayRequestWin
NAME
MX_DisplayRequestWin -- display a request to the user (V24)
SYNOPSIS
result = MX_DisplayRequestWin(body,buttons,data,window)
d0 a0 a1 a2 d0
ULONG result;
STRPTR body;
STRPTR buttons;
APTR data;
struct Window *window;
FUNCTON
Displays a request to the user either by an intuition
requestor.
INPUTS
body = pointer to format string for the body text. If
NULL then this function performs no action.
buttons = pointer to format string for the buttons
data = data for the formatting strings
window = pointer to window to disable.
RESULT
0, 1, ..., N = Successive GadgetID values, for the gadgets
you specify for the requester. NOTE: The numbering
from left to right is actually: 1, 2, ..., N, 0.
SEE ALSO
MX_DisplayRequest(), exec.library/RawDoFmt(),
intuition.library/EasyRequestArgs() dos.library/VPrintf()
matrix.library/MX_DosOpen matrix.library/MX_DosOpen
NAME
MX_DosOpen -- open a file
SYNOPSIS
filehandle = MX_DosOpen(filename,path,mode)
d0 a0 a1 d0
INPUTS
filename =
path =
mode =
RESULT
filehandle is NULL if file could not be opened
SEE ALSO
dos.library/Open(), dos.library/Close()
matrix.library/MX_ExamineDir matrix.library/MX_ExamineDir
NAME
MX_ExamineDir -- examine entries in a directory (V21)
SYNOPSIS
lock = MX_ExamineDir(hook,[data],lock)
d0 a0 d0 d1
BPTR lock;
APTR hook;
BPTR lock;
LONG data;
FUNCTION
Examine a directory
INPUTS
hook = pointer to hook function called as follows:
continue = Hook(fib,data)
d0 a0 d0
BOOLEAN continue;
struct FileInfoBlock *fib;
LONG data;
The hook function should return 0 for abort, and 1 to
continue with the directory read.
lock = pointer to a directory that has been locked.
data = user definable value passed to hook function.
RESULT
lock = the same value as the lock passed in.
NOTES
This function will change the CurrentDir to the directory
being examined (V23)
BUGS
Prior to V23 the hook function did not return a continuation
condition, this has been added to V23. Some programs will
not function correctly and should be updated.
SEE ALSO
dos.library/Lock(), dos.library/Examine(), dos.library/ExNext(),
dos.library/CurrentDir()
matrix.library/MX_Free8SVX matrix.library/MX_Free8SVX
NAME
MX_Free8SVX -- OBSOLETE FUNCTION
SYNOPSIS
MX_Free8SVX(mx8SVX)
d0
matrix.library/MX_FreeArgs matrix.library/MX_FreeArgs
NAME
MX_FreeArgs -- Free allocated memory after MX_ReadArgs() (V23)
SYNOPSIS
MX_FreeArgs(MXArgLock)
a0
struct *MXArgLock;
INPUTS
MXArgLock - pointer returned by MX_ReadArgs or NULL for no action.
RESULT
None.
SEE ALSO
matrix.library/MX_FreeArgs(), dos.library/FreeArgs()
dos.library/ReadArgs(), dos.library/ReadItem(), dos.library/FindArg()
matrix.library/MX_FreeFIB matrix.library/MX_FreeFIB
NAME
MX_FreeFIB -- deallocate the FIB from MX_LoadFIB()
SYNOPSIS
MX_FreeFIB(fib)
d0
SEE ALSO
MX_LoadFIB, dos.library/AllocDosObject(), dos.library/Examine()
matrix.library/MX_FreeFont matrix.library/MX_FreeFont
NAME
MX_FreeFont -- Frees the font allocated. (V23)
SYNOPSIS
MX_FreeFont(textattr,font,tags)
a0 a1 a2
struct TextAttr *textattr;
struct TextFont *font;
struct TagItem *tags;
FUNCTION
Frees any resources taken by MX_GetFont(). The
textattr structure will be initialized to zeros.
INPUTS
textattr = pointer to textattr structure that was filled
by MX_GetFont().
font = as returned by MX_GetFont().
tags = pointer to a taglist (NULL).
TAGS
None.
RESULT
None.
SEE ALSO
MX_GetFont(), graphics.library/CloseFont()
matrix.library/MX_FreeList matrix.library/MX_FreeList
NAME
MX_FreeList -- free the entire list (V22)
SYNOPSIS
MX_FreeList(list,hook,[userdata])
a0 a1 [d0]
APTR head;
APTR hook;
LONG userdata;
FUNCTION
Frees an entire list.
INPUTS
head = pointer to list head or NULL.
hook = pointer to hook function. See MX_FreeListNodes().
RESULT
None.
NOTES
The list head is not freed by the user function, it is freed
using exec.library/FreeVec(). The userdata parameter was added for
V23 matrix.library.
SEE ALSO
exec.library/FreeVec(), MX_FreeListNodes()
matrix.library/MX_FreeListNodes matrix.library/MX_FreeListNodes
NAME
MX_FreeListNodes -- free the nodes of a linked list (V22)
SYNOPSIS
MX_FreeListNodes(head,hook,[userdata])
a0 a1 [d0]
APTR head;
APTR hook;
LONG userdata;
FUNCTION
Frees all nodes from a linked list, using specified userhook or
internal routines.
INPUTS
head = pointer to list head.
hook = pointer to hook function. If this is NULL then the node
is freed using exec.library/FreeVec(), otherwise the userhook
called as UserHook(node,userdata)(a1,d0).
RESULT
None.
NOTES
The userdata parameter was added for V23 matrix.library and is
an optional parameter.
SEE ALSO
exec.library/FreeVec(), MX_FreeList(), MX_TextFileToList()
matrix.library/MX_FreeMem matrix.library/MX_FreeMem
NAME
MX_FreeMem -- OBSOLETE FUNCTION
SYNOPSIS
MX_FreeMem(mem)
a1
matrix.library/MX_FullWBArgName matrix.library/MX_FullWBArgName
NAME
MX_FullWBArgName -- full path name of wb argument (V21)
SYNOPSIS
success = MX_FullWBArgName(buffer,wbarg,len)
d0 a0 a1 d0
ULONG success;
STRPTR buffer;
struct WbArg *wbarg;
ULONG len;
INPUTS
buffer = pointer to the buffer to fill with the path name.
wbarg = the wb argument (see workbench.library)
len = length of the buffer.
RESULT
returns TRUE if successful.
NOTES
If the path is 'SPAM:' then this will be expanded to
'SPAM:disk'.
SEE ALSO
workbench.library
matrix.library/MX_GetCatalogStr matrix.library/MX_GetCatalogStr
NAME
MX_GetCatalogStr -- get a localized string (V24)
SYNOPSIS
string = MX_GetCatalogStr(catalog,catCompArray,stringNum)
d0 a0 a1 d0
FUNCTION
Localizes a string id if required.
INPUTS
catalog = a message catalog.
catCompArray = pointer to catCompArray
stringNum = a message number within the catalog
RESULT
string = a pointer to a NULL-terminated string. The returned string
is READ-ONLY, do NOT modify! This string pointer is valid only
as long as the catalog remains open.
NOTE
If the CatCompArray is NULL then the STRPTR returned is
actually the stringNum passed in. Make sure you have a
pointer to a valid CatCompArray.
The CatCompArray is of the following format:
ULONG id ; id number
STRPTR string ;
.
.
.
ULONG NULL
If the first longword of the CatCompArray is -1 then the
array is treated as a packed list of the following format
ULONG id ; id number
UWORD len ; length of string
UBYTE string[len] ; always an even length, single or double null terminated
.
.
.
ULONG NULL
SEE ALSO
locale.library/GetCatalogStr()
matrix.library/MX_GetFont matrix.library/MX_GetFont
NAME
MX_GetFont -- Fills out textattr structure. (V22)
SYNOPSIS
font = MX_GetFont(textattr,tags)
d0 a0 a1
struct Font *font;
struct TextAttr *textattr;
struct TagItem *tags;
FUNCTION
Fills out a text attribute structure based on the
default system font. The font pointer returned may
be null. In wich case the textattr structure will
be filled out to "topaz.font", size 8. It is not
necessary to call MX_FreeFont() if the font
returned is NULL.
INPUTS
textattr = pointer to textattr structure to be filled.
tags = pointer to a taglist (NULL).
TAGS
MXGF_FontName (UBYTE *) - pointer to name of font to open.
This tag is mutually inclusive to MXGF_FontSize. The
default for this is the system font. An additional
extension has been provided, you may specify the
fontname and size in the same string using a space
as a separator.
Example: "topaz.font 8" or "topaz 8"
MXGF_FontSize (WORD) - size of the font to open. This tag
is mutually inclusive to MXGF_FontName. The defaut
for this is the system font.
MXGF_FontSizeStr (STRPTR) - this is functionally the same
as MXGF_FontSize except that a string pointer is used.
MXGF_UseScreenFont (struct Screen *) - pointer to the
screen to obtain the font. This will overide the
default for MXGF_FontName and MXGF_FontSize is no
name and size are specified. (V23)
RESULT
font = pointer to font opened or NULL.
SEE ALSO
MX_FreeFont(), diskfont.library/OpenDiskFont()
matrix.library/MX_HexStrLong matrix.library/MX_HexStrLong
NAME
MX_HexStrLong -- convert hex string to long (V19)
SYNOPSIS
value, success, next = MX_HexStrLong(string)
d0 d1 a0 a0
STRPTR string;
ULONG value;
INPUTS
string - pointer to valid hexadecimal string. This string
may only contain a maximum of 8 characters selectable
from "0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f".
RESULT
value = the value of the hexidecimal string.
success = indication on wether the conversion was
successful or not.
next = pointer to the next byte to be processed in the
string after the converted characters.
NOTE
SEE ALSO
matrix.library/MX_HookTag matrix.library/MX_HookTag
NAME
MX_HookTag -- call hook function from tag array (V23)
SYNOPSIS
result = MX_HookTag(tagarray,defhook,tagvalue,data)
d0 a0 a1 d0 d1
struct TagItem *tagarray;
APTR defhook;
LONG tagvalue;
LONG data;
INPUTS
tagarray - pointer to array of tag items. The hook
function is called as follows:
Hook(data)(d0)
defhook - hook to call if tag item not found.
tagvalue - value of the tag item hook to call.
data - data passed to hook function.
RESULT
return value from hook function or NULL if no hook function
was invoked.
NOTES
When the hook function is called registers a4 and a5
are untouched.
SEE ALSO
MX_HookTagOrdered, utility.library/GetTagData()
matrix.library/MX_HookTagOrdered matrix.library/MX_HookTagOrdered
NAME
MX_HookTagOrdered -- call hook function from tag array (V23)
SYNOPSIS
MX_HookTagOrdered(tagarray,defhook,tagvalue,data)
a0 a1 d0 d1
struct TagItem *tagarray;
APTR defhook;
LONG tagvalue;
LONG data;
FUNCTION
This routine is functions identically to MX_HookTag()
except that the array must be in order.
INPUTS
tagarray - pointer to array of tag items. The hook
function is called as follows:
Hook(data)(d0)
defhook - hook to call if tag item not found.
tagvalue - value of the tag item hook to call.
data - data passed to hook function.
RESULT
None.
SEE ALSO
MX_HookTag, utility.library/GetTagData()
matrix.library/MX_JustifyText matrix.library/MX_JustifyText
NAME
MX_JustifyText -- justtify a buffer
SYNOPSIS
MX_JustifyText(source,dest,length)
a0 a1 d0
APTR source;
APTR dest;
ULONG length;
FUNCTION
INPUTS
source - pointer to source buffer to justify
dest - pointer to buffer to store the justified source buffer
length - length of the justify buffer
RESULT
None
NOTE
The source buffer must not exceed the length of the justfy.
It is intended that the MX_WrapText() function be used before
calling this routine to remove any partial word left on the
end of the line. Any trailing spaces will be removed by this
routine.
BUGS
SEE ALSO
MX_WrapText()
matrix.library/MX_ListToArray matrix.library/MX_ListToArray
NAME
MX_ListToArray -- convert a list into an array (V23)
SYNOPSIS
array,numelements = MX_ListToArray(list,tags,numElements)
d0 d1 a0 a1 d0
FUNCTION
Converts a list into array form, the array consists of
pointers to the list nodes, terminated with a NULL pointer
to indicate end of list.
INPUTS
list = pointer to list.
tags = pointer to a tag item array.
numelements = number of elements in the list, if 0 then
the list will be traversed to calculate the number of
entries. This value MUST NOT be less than the number
of list entries.
TAGS
MXLTA_AddOffset (WORD) = offset relative to the node to
use as the pointer. Default is 0.
RESULT
Pointer to array of pointers to list nodes, use
exec.library/FreeVec() to deallocate.
SEE ALSO
MX_QuickSort()
matrix.library/MX_Load8SVX matrix.library/MX_Load8SVX
NAME
MX_Load8SVX -- OBSOLETE FUNCTION
SYNOPSIS
MX_Load8SVX(filename,tags)
a0 d0
matrix.library/MX_LoadFIB matrix.library/MX_LoadFIB
SYNTAX
fib,typedata = MX_LoadFIB(type,typedata)
d0 d1 d0 d1
INPUTS
type - specification of typedata, can be:
LOADFIB_LOCK
LOADFIB_FILEHANDLE
LOADFIB_NAME
typedata - lock, filehandle or pointer to filename.
RESULTS
fib - pointer to fileinfo block, NULL if failed. Use MX_FreeFib()
to discard this fib when finished.
SEE ALSO
MX_FreeFIB, dos.library/AllocDosObject(), dos.library/Examine()
matrix.library/MX_LoadFile matrix.library/MX_LoadFile
SYNTAX
buffer,length = MX_LoadFile(filename)
d0 d1 a0
INPUTS
filename = pointer to name fo file to load
RESULTS
buffer = pointer to buffer file read into, this is padded with a
NULL byte. This is NULL if there is an error. To deallocate
this buffer use exec.library/FreeVec().
length = the number of bytes successfully read (this is not the
length of the buffer).
SEE ALSO
exec.library/FreeVec()
matrix.library/MX_LoadIFF matrix.library/MX_LoadIFF
NAME
MX_LoadIFF() -- OBSOLETE
SYNOPSIS
iffhandle = MX_LoadIFF(iffhandle,filename,tags)
d0 a0 a1 a2
matrix.library/MX_LockMxBase matrix.library/MX_LockMxBase
NAME
MX_LockMxBase -- Invoke semaphore arbitration of MxBase.
SYNOPSIS
MX_LockMxBase()
FUNCTION
This locks the MxBase so the data may be read/modified.
INPUTS
None.
RESULT
None.
NOTE
This call is guaranteed to preserve all registers.
A call to this function MUST be paired with a subsequent
call to MX_UnlockMxBase(), and soon, please.
Do not call any Matrix functions while holding this
lock, except for MX_UnlockMxBase().
SEE ALSO
MX_UnlockMxBase()
matrix.library/MX_MakeMenu_Localize matrix.library/MX_MakeMenu_Localize
NAME
MX_MakeMenu_Localize -- make menus localized
SYNOPSIS
newmenu= MX_MakeMenu_Localize(newmenu, catalog, catCompArr,tags)
d0 a0 a1 a2 d0
struct NewMenu *newmenu
struct NewMenu *newmenu
struct Catalog *catalog
APTR catCompArr
struct TagItem *tags
FUNCTION
Make a menu using locale id's
INPUTS
newwmenu - pointer to GadTools NewMenu structure.
catalog - pointer to locale catalog returned by
locale.library/OpenCatalog().
catCompArr - array of locale strings
tags - pointer to taglist.
RESULT
pointer to a localize newmenu array or NULL for failure.
SEE ALSO
gadtools.library/CreateMenusA(), locale.library/OpenCatalog()
matrix.library/MX_MakePath matrix.library/MX_MakePath
NAME
MX_MakePath -- create an entire directory path (V22)
SYNOPSIS
success = MX_MakePath(path)
d0 a0
BOOL success;
STRPTR path;
INPUTS
path = pointer to path string.
RESULT
success = 0 if failure occurs.
SEE ALSO
dos.library/CreateDir(), MX_DeleteDirectory()
matrix.library/MX_ModifyListview matrix.library/MX_ModifyListview
NAME
MX_ModifyListview -- change the list in a listview.
SYNOPSIS
MX_ModifyListview(gad,win,hook,data)
a0 a1 a2 d0
struct Gadget *gad;
struct Window *win;
APTR hook;
LONG data;
FUNCTION
Modifys a listview list, disables the list so that it may be
modified and calls a hook function. The hook function returns a
pointer to a list (generally the old list but modified.) The
listview is then set to the new list. If no hook function is
specified then the data parameter is used as the new list pointer.
INPUTS
gad - pointer to a listview gadget.
win - pointer to a window.
hook - pointer to user hook function or NULL. The hook function
is called as follows:
list = hook(data)
d0 d0
data - if a hook function is provided then this is treated as
a user data field, otherwise is the hook pointer is NULL this
is used as a pointer to a list.
RESULT
None.
NOTES
If the gad and win pointers are both NULL then the hook function
will still be called, just that no gadget will be updated.
SEE ALSO
gadtools.library/GT_SetGadgetAttrsA()
matrix.library/MX_NewLoadIFF matrix.library/MX_NewLoadIFF
NAME
MX_NewLoadIFF -- load an IFF form file (V23)
SYNOPSIS
success = MX_NewLoadIFF(filename,tags)
d0 a0 a1
ULONG success;
STRPTR filename;
struct TagItem *tags;
FUNCTION
Reads an iff FORM file given a hunk definition.
INPUTS
filename = pointer to name of file to open.
tags = pointer to taglist.
RESULT
success = TRUE if file load was completed successfully.
TAGS
MXIF_Filename (UBYTE *) - pointer to name of file to open, this
overides the parameter passed to this function.
MXIF_Type (ULONG) - type of IFF file to process. Eg "PREF".
MXIF_HunkArray (APTR) - pointer to NULL terminated array of hunk
descriptors. The hunk descriptor is a structure as follows
ULONG - Hunk name (Eg. "PRHD" )
ULONG - Hunk type
ULONG - Data0
ULONG - Data1
MXIF_ValidateHook (APTR) - pointer to hook function called when
the IFF file has been loaded.
success = ValidateHook()
SUPPORTED HUNK TYPES
MXIF_Raw
MXIF_HookMULTI
MXIF_HookOWNCHUNK
MXIF_STRING
SEE ALSO
MX_NewSaveIFF()
matrix.library/MX_NewPrefsWH matrix.library/MX_NewPrefsWH
NAME
MX_NewPrefsWH -- process window as a preferences program (V23)
SYNOPSIS
result = MX_NewPrefsWH(tags)
d0 a0
ULONG result;
struct TagItem *tags;
FUNCTION
Handles all processing for a standard workbench style preferences
program. All standard preferences operations are supported, such
as the loading, saving and restoring of data, menu functions and
load/save as file requestors.
INPUTS
tags = pointer to taglist.
RESULT
result = 0,1,2 (Cancel,Use,Save)
TAGS
MXPF_AboutMenuHook (void *) - pointer to hook function to handle
selection of the about menu item. You do not get an about menu
item if this tag is NULL. Default NULL.
MXPF_ASLInfo (WORD *) - a pointer to 4 words containing the asl file
requestor positional and dimensional information.
MXPF_DefaultHook (APTR) - this hook is called when the default
settings has been selected from the menu.
MXPF_Font (STRPTR) - pointer to fontname to use for gadgets etc...
If null then the default system font will be used.
MXPF_IFFTags (APTR) - pointer to tag array for MX_NewLoadIFF() and
MX_NewSaveIFF().
MXPF_InitialLoad (BOOLEAN) - set this to TRUE to load the initial
preferences settings. Default = TRUE.
MXPF_LoadSaveDir (UBYTE *) - pointer to default directory for the
Open and Save filerequestors to go to.
MXPF_LoadTitle (UBYTE *) - this string overides the MXPF_Title for
the Open file requestor.
MXPF_NewDataHook (APTR) - this hook is called when the preferences
data is loaded or reset.
MXPF_PreSaveHook (APTR) - pointer to user function called before
any file saving operations. NOTE: It is called only once when
the user selects SAVE and the ENVARC: and ENV: files are
written. This hook is also called when the user selects
"Save As..." from the menu.
MXPF_PubScreenName (UBYTE *) - pointer to public screen name. If no
screen name is provided then the default public screen is used.
MXPF_QuitMenuHook (void *) - pointer to hook function invoked when
quit is selected from the menu. Default = Cancel the prefs.
MXPF_SaveFile (UBYTE *) - filename to save the preferences as.
MXPF_SaveTitle (UBYTE *) - this string overides the MXPF_Title for
the Save file requestor.
MXPF_Screen (struct Screen *) - pointer to screen to open on. If no
visual info tag is provided then the visual info will be
obtained automatically.
MXPF_Title (UBYTE *) - default name to be used in Open and Save file
requestors. The title will be inserted as:
"Load %s Preferences" and "Save %s Preferences"
MXPF_UseFile (UBYTE *) - file name to use the preferences as, this
is also the name used to load the initial preferences settings.
MXPF_VisualInfo (APTR) - pointer to screen visual info returned by
gadtools/GetVisualInfoA().
MXPF_WHTags (struct TagItem *) - pointer to standard matrix
windowhandler tag item array. See MX_WindowHandler().
MXPF_Window (struct Window *) - pointer to parent window. You need
to specify MXPF_VisualInfo if you are using this tag.
Currently this tag has not been implemented.
SEE ALSO
MX_PrefsWH(), MX_NewLoadIFF(), MX_NewSaveIFF(), MX_WindowHandler(),
MX_WindowHandler2(), intuition.library/OpenWindowTagList(),
gadtools.library/GetVisualInfoA()
matrix.library/MX_NewReadArgs matrix.library/MX_NewReadArgs
NAME
MX_NewReadArgs -- Parse the arguments (V23)
SYNOPSIS
MXArgLock = MX_NewReadArgs(template,array,tags)
d0 a0 a1 a2
struct *MXArgLock;
STRPTR *template;
LONG *array;
struct TagItem *tags;
INPUTS
template = see dos.library/ReadArgs() for details. Currently only a
subset of the dos template types are supported for tool types,
they are: /K, /N, /K/N, and /S
array = array of longwords for results, 1 per template entry
tags = pointer to a tag list or NULL.
RESULT
MXArgLock - NULL for failure. Call MX_FreeArgs with this pointer to
deallocated any resources used.
TAGS
MXRA_DosFallback (BOOLEAN) - fallback to processing the dos cli
arguments when we are run from cli. This is only valid when the
tool types have been set by MXRA_TryLoadIcon and allow the tool
types to act as set values and any cli arguments will overide
these values. Defaults to TRUE. (V24)
MXRA_ToolTypes (APTR) - pointer to tool type array to use instead of
using the tooltypes from WBStartup message. (V23)
MXRA_TryLoadIcon (BOOLEAN) - if TRUE then the icon for the program
will be loaded and used for argument processing if no tool types
were provided by any other means. (V23)
MXRA_WBMessage (APTR) - pointer to WBStartup message. This is used to
set the tool types array if it was not provided by MXRA_ToolTypes.
(V23)
SEE ALSO
MX_ReadArgs(), MX_FreeArgs(), dos.library/ReadArgs()
dos.library/FindArg(), dos.library/ReadItem(), dos.library/FreeArgs()
matrix.library/MX_NewSaveIFF matrix.library/MX_NewSaveIFF
NAME
MX_NewSaveIFF -- save an IFF form file (V23)
SYNOPSIS
success = MX_NewSaveIFF(filename,tags)
d0 a0 a1
ULONG success;
STRPTR filename;
struct TagItem *tags;
FUNCTION
Writes an iff FORM file given a hunk definition.
INPUTS
filename = pointer to name of a new file to open.
tags = pointer to taglist.
RESULT
success = TRUE if file save was completed successfully.
TAGS
MXIF_CreateDir (BOOLEAN) - if the directory for the file
does not exist then an attempt will be made to make
the directory. If successful then the file open will
be reattempted.
see MX_NewLoadIFF() for additional tags
SEE ALSO
MX_NewLoadIFF()
matrix.library/MX_NewSortList matrix.library/MX_NewSortList
NAME
MX_NewSortList() -- sort a list (v23)
SYNOPSIS
success = MX_NewSortList(list,hook,tags,elements,data)
d0 a0 a1 a2 d0 d1
FUNCTION
Sort a linked list using a callback hook for node
comparisions.
INPUTS
list = pointer to a list to be sorted
hook = comparison hook function called as follows:
result/d0 = hook(node1,node2,data)(a0,a1,a6)
-1 = node1 > node 2
0 = same
1 = node1 < node 2
If the hook is NULL then a default hook is
used which compares the LN_NAME strings and
is case sensitive.
tags = pointer to taglist, NULL.
elements = number of elements in the array, if NULL then
the list will be traversed to compute the number of
elements. If provided, this *MUST* be at least the
number of elements in the list.
data = passed to hook function in a6
RESULT
FALSE if list was not sorted.
TAGS
None
NOTES
The sorting algorithm currently used is QuickSort.
SEE ALSO
MX_SortList(), MX_QuickSort()
matrix.library/MX_NextForm matrix.library/MX_NextForm
NAME
MX_NextForm -- OBSOLETE FUNCTION
SYNOPSIS
MX_NextForm(formhandle)
a0
matrix.library/MX_OpenForm matrix.library/MX_OpenForm
NAME
MX_OpenForm -- OBSOLETE FUNCTION
SYNOPSIS
formhandle = MX_OpenForm(name,type,mode,tags)
d0 a0 a1 d0 d1
matrix.library/MX_OpenFormReq matrix.library/MX_OpenFormReq
NAME
MX_OpenFormReq -- OBSOLETE FUNCTION
SYNOPSIS
formhandle = MX_OpenFormReq(hail,path,file,type,mode,tags)
d0 a0 a1 a2 a3 d0 d1
matrix.library/MX_OpenPathNew matrix.library/MX_OpenPathNew
NAME
MX_OpenPathNew -- open a file as NEW (V23)
SYNOPSIS
fh = MX_OpenPathNew(name)
d0 a0
struct filehanle *fh;
STRPTR name;
FUNCTION
Opens a file creating the path if necessary.
INPUTS
name = pointer to filename, if the path cannot be locked then
an attempt is made to create that path. If it is not
possible to make the path then this function returns
FALSE as the file cannot be opened as NEW. If the path
exists then This function is similar to
fh = Open(filename,MODE_NEWFILE);
RESULT
Returns FALSE if unable to open file or create path to file.
SEE ALSO
dos.library/Open(), dos.library/Close()
matrix.library/MX_PatternMatch matrix.library/MX_PatternMatch
NAME
MX_PatternMatch -- perform dos patternmatching on a string. (V23)
SYNTAX
result = MX_PatternMatch(string,pattern)
d0 a0 a1
LONG result;
STRPTR string;
STRPTR pattern;
FUNCTION
Matches the string against the specified pattern.
INPUTS
string = pointer to string.
pattern = pointer to pattern for pattern matching.
RESULT
result = success or failure of pattern match. Returns ~0
if run out of memory/stack.
NOTES
The pattern matching is not case sensitive.
SEE ALSO
dos.library/ParsePatternNoCase(), dos.library/MatchPatternNoCase()
matrix.library/MX_ProcessArexxPort matrix.library/MX_ProcessArexxPort
NAME
MX_ProcessArexxPort -- process arexx messages (V23)
SYNTAX
MX_ProcessArexxPort(port,vectors,[userdata])(a0,a1,[d0])
struct MsgPort *port;
APTR *vectors;
ULONG userdata;
FUNCTION
Process any messages arriving at an arexx port through Hook
functions.
INPUTS
port = pointer to an arexx message port. You can easily create
an arexx message port by calling MX_AddArexxPort().
vectors = pointer to an array of pointers to command strings
and hook functions, terminated by a command string pointer
of null.
The hook function is called as follows:
result = Hook(msg,args,userdata)
d0 a0 a1 d0
userdata = optional parameter, this is passed to the hook
function.
RESULT
None.
SEE ALSO
MX_AddArexxPort(), MX_RemArexxPort()
matrix.library/MX_QuickSort matrix.library/MX_QuickSort
NAME
MX_QuickSort() -- sort an array (v23)
SYNOPSIS
MX_QuickSort(array,hook,elements,data)
a0 a1 d0 d1
FUNCTION
Sort an array using callback hook.
INPUTS
array = pointer to an array of longwords, when this
is called by MX_NewSortList() this is an array of
pointers to nodes.
hook = comparison hook function called as follows:
result/d0 = hook(e1,e2,data)(a0,a1,a6)
-1 = e1 > e2
0 = same
1 = e1 < e2
elements = number of elements in the array, if NULL then
the list will be traversed to compute the number of
elements. If provided, this *MUST* be at least the
number of elements in the list.
data = passed to user hook function in a6
RESULT
None.
SEE ALSO
MX_NewSortList(), MX_ListToArray()
matrix.library/MX_Random matrix.library/MX_Random
NAME
MX_Random -- generate a random number (V22)
SYNOPSIS
number = MX_Random(range)
d0 d0
LONG number;
LONG range;
INPUTS
range = the largest number to generate. The generated number will
fall in the range from 0 to "range"
RESULT
number = the random number generated.
SEE ALSO
MX_RandomSeed(), MX_RandomInRange()
matrix.library/MX_RandomInRange matrix.library/MX_RandomInRange
NAME
MX_RandomInRange -- generate a random number (V23)
SYNOPSIS
number = MX_RandomInRange(min,max)
d0 d0 d1
LONG number;
LONG min;
LONG max;
INPUTS
min = the minimum value to generate
max = the maximum value to generate
RESULT
number = a randomly generated number greater or equal to
min and less or equal to max:
min =< number =< max
SEE ALSO
MX_RandomSeed(), MX_Random()
matrix.library/MX_RandomSeed matrix.library/MX_RandomSeed
NAME
MX_RandomSeed -- seed the random number tables. (V22)
NOTES
This function is private for use by matrix.library only.
SEE ALSO
MX_Random(), MX_RandomInRange()
matrix.library/MX_RawFormat matrix.library/MX_RawFormat
NAME
MX_RawFormat -- format data into a character stream. (V21)
SYNOPSIS
NextData = MX_RawFormat(FormatString,DataStream,Destination)
d0 a0 a1 a2
APTR NextData;
STRPTR FormatString;
APTR DataStream;
APTR Destination;
FUNCTION
This function is identical to the exec.library/RawDoFmt() function
except it does not require the PuchChProc.
INPUTS
FormatString - a "C"-language-like NULL terminated format string.
DataStream - a stream of data that is interpreted according to the
format string. Often this is a pointer into the task's stack.
Destination - pointer to a buffer to fill with the formatted
string.
RESULT
NextData = pointer to end of the data stream, this allows multiple
formatting passes to be made using the same data.
SEE ALSO
exec.library/RawDoFmt().
matrix.library/MX_ReadArgs matrix.library/MX_ReadArgs
NAME
MX_ReadArgs -- Parse the command line / wbmsg input (V23)
SYNOPSIS
MXArgLock = MX_ReadArgs(template,array,[wbmsg])
d0 a0 a1 [a2]
struct *MXArgLock;
STRPTR *template;
LONG *array;
struct *WBMessage wbmsg;
INPUTS
template - see dos.library/ReadArgs() for details on definition of
the template. Currently supported supported tool types are
"/K, /N, /K/N, and /S".
array - array of longwords for results, 1 per template entry
wbmsg - pointer to message from workbench, this only needs to be
provided if you were not started from CLI.
RESULT
MXArgLock - NULL for failure. Call MX_FreeArgs with this pointer to
deallocated any resources used.
NOTES
This function is obsolete, use MX_NewReadArgs() instead.
SEE ALSO
MX_NewReadArgs(), MX_FreeArgs(), dos.library/ReadArgs()
dos.library/FindArg(), dos.library/ReadItem(), dos.library/FreeArgs()
matrix.library/MX_ReadForm matrix.library/MX_ReadForm
NAME
MX_ReadForm -- OBSOLETE FUNCTION
SYNOPSIS
MX_ReadForm(formhandle,buffer,size)
a0 a1 d0
matrix.library/MX_ReadFormTagList matrix.library/MX_ReadFormTagList
NAME
MX_ReadFormTagList -- OBSOLETE FUNCTION
SYNOPSIS
MX_ReadFormTagList(formhandle,buffer,size,tags)
a0 a1 d0 d1
matrix.library/MX_RemArexxPort matrix.library/MX_RemArexxPort
NAME
MX_RemArexxPort -- remove a public arexx message port. (V23)
SYNOPSIS
MX_RemArexxPort(port,hook,[userdata])
a0 a1 [d0]
struct MsgPort *port;
APTR hook;
FUNCTION
Remove an arexx port from the system safely, replying any waiting
messages using ReplyMsg() or userhook().
INPUTS
port - pointer to port added using MX_AddArexxPort(). May be NULL.
hook - pointer to user function that is called to reply any messages
waiting at this port. If NULL then the message will be replied
using ReplyMsg(). The userhook is invoked as follows:
userhook(msg,userdata)
a1 d0
RESULT
None.
SEE ALSO
MX_AddArexxPort(), MX_ProcessArexxPort(), exec.library/RemPort(),
exec.library/DeleteMsgPort(), exec.library/ReplyMsg().
matrix.library/MX_RemVBlankNode matrix.library/MX_RemVBlankNode
NAME
MX_RemVBlankNode -- remove vblank node hook or signal (V23)
SYNOPSIS
MX_RemVBlankNode(vbn)
a0
struct MXVBlankNode *vbn;
FUNCTION
Remove an added MXVBlank node.
INPUTS
vbn = pointer to MXVBlankNode to remove or NULL.
RESULT
None.
SEE ALSO
MX_AddVBlankNode(), MX_UpdateVBLankInterrupt()
matrix.library/MX_RemakeGadgets matrix.library/MX_RemakeGadgets
NAME
MX_RemakeGadgets -- update the gadgets (V22)
SYNOPSIS
MX_RemakeGadgets(gadgets,window)
d0 a0
struct Gadget *gadgets;
strcut Window *window;
FUNCTION
Remakes the gadgets when the data changes.
INPUTS
gadgets = pointer to gadgets created by MX_CreateGadgets().
If NULL then the gadget pointer from the window will
be used.
window = pointer to window gadgets are in.
RESULT
None.
SEE ALSO
MX_CreateGadgets(), MX_CleanUpGList()
matrix.library/MX_ReplaceTags matrix.library/MX_ReplaceTags
NAME
MX_ReplaceTags -- change the tag values in a tag array (V24)
SYNOPSIS
MX_ReplaceTags(tagArray,replaceArray,flags)
a0 a1 d0
struct TagItem *tagArray;
APTR replaceArray;
ULONG flags;
FUNCTION
Changes the tag value id's in a tag array to those specified
by the replacement array.
INPUTS
tagArray - pointer to a valid tag item array.
replaceArray - an array of ULONG tag id pairs, the first is
the source tag to search for and the second is its
replacement tag id.
flags - NULL. None defined.
RESULT
None.
NOTES
Tags not found in the replacement array are marked TAG_IGNORE.
SEE ALSO
matrix.library/MX_ReplaceVecStr matrix.library/MX_ReplaceVecStr
NAME
MX_ReplaceVecStr -- alloc/update a string and buffer (V23)
SYNOPSIS
mem = MX_ReplaceVecStr(string,handle,attributes)
d0 a0 a1 d1
APTR mem;
STRPTR string;
APTR *handle;
ULONG attributes;
FUNCTION
Allocates a buffer for the string and copys the string into
the buffer. Frees the old buffer pointed to by the handle, and
updates the handle to point to the new buffer.
INPUTS
string = pointer to a string.
handle = pointer to storage space for string pointer.
attributes = exec.library/AllocVec() memory attributes.
RESULT
Pointer to buffer containing the string, or NULL if not enough
memory for the buffer.
NOTE
Use exec.library/FreeVec() to deallocate the buffer.
SEE ALSO
MX_AllocVecStr(), exec.library/AllocVec(), exec.library/FreeVec()
matrix.library/MX_SaveIFF matrix.library/MX_SaveIFF
NAME
MX_SaveIFF() -- OBSOLETE
SYNOPSIS
result = MX_SaveIFF(iffhandle,filename,tags)
d0 a0 a1 a2
matrix.library/MX_SeekForm matrix.library/MX_SeekForm
NAME
MX_SeekForm -- OBSOLETE FUNCTION
SYNOPSIS
MX_SeekForm(formhandle,pos,mode)
a0 d0 d1
matrix.library/MX_SelectGadget matrix.library/MX_SelectGadget
NAME
MX_SelectGadget -- show a gadget being selected
SYNOPSIS
MX_SelectGadget(window,gadget)
a0 a1
struct Window *window;
struct Gadget *gadget;
FUNCTION
INPUTS
window = pointer to window containing gadget
gadget = pointer to the gadget to show being selected
RESULT
None
BUGS
SEE ALSO
matrix.library/MX_SendArexxString matrix.library/MX_SendArexxString
NAME
MX_SendArexxString -- send a command to an arexx port (V20)
SYNOPSIS
res1,res2,port = MX_SendArexxString(string,portname,replyport)
d0 d1 a0 a0 a1 a2
ULONG res1;
ULONG res2;
STRPTR string;
STRPTR pointname;
struct MsgPort *replyport;
FUNCTION
Sends an arexx message to an arexx port and waits for the
reply.
INPUTS
string - pointer to null terminated string to send to specified
arexx message port.
portname - name of arexx message port to send message to.
replyport - NULL. [Not Supported]
RESULT
res1,res2 = return values from arexx message or -1 if failed.
SEE ALSO
exec.library/FindPort(), exec.library/PutMsg()
rexxsyslib.library/CreateRexxMsg(), rexxsyslib.library/CreateArgstring
rexxsyslib.library/FillRexxMsg, rexxsyslib.library/ClearRexxMsg
rexxsyslib.library/DeleteRexxMsg
matrix.library/MX_SetListView matrix.library/MX_SetListView
NAME
MX_SetListView -- change/disable list and enable/disable gadget (V23).
SYNOPSIS
MX_SetListView(gad,win,list,entry)
a0 a1 d0 d1
struct Gadget *gad;
struct Window *win;
struct List *list;
WORD entry;
FUNCTION
Changes the list being used by the listview gadget and enables
or disables the list if there are entries in it or not.
INPUTS
gad = pointer to the listview gadget or NULL for no action.
win = pointer to the window or NULL for no action.
list = pointer to a list or ~0 to disable the current
list. If NULL then the listview will be disabled.
entry = entry number in the list to set active.
RESULT
None.
SEE ALSO
gadtools.library/GT_SetGadgetAttrsA()
matrix.library/MX_SetWaitPointer matrix.library/MX_SetWaitPointer
NAME
MX_SetWaitPointer -- make the pointer a busy pointer
SYNOPSIS
MX_SetWaitPointer(?)
FUNCTION
INPUTS
?
RESULT
None
NOTE
BUGS
SEE ALSO
matrix.library/MX_ShowWindow matrix.library/MX_ShowWindow
NAME
MX_ShowWindow -- show window active by a task (V23)
SYNOPSIS
MX_ShowWindow(window,[task])
a0 a1
struct Window *window;
struct Task *task;
FUNCTION
Will make a window visible to the user by all means possible. If
no window pointer is given then the task pointer is used and
the pr_WindowPtr() field is extracted and used as the window
pointer.
INPUTS
window = pointer to the window to show or NULL.
task = pointer to task to use pr_WindowPtr(). You only need to
specify this field if window is NULL. This may also be NULL,
in which case nothing will happen.
RESULT
The window (if any) will be brought to the fron of the screen
it is on, unzipped (if zipped) and the screen will come to
the front of the display.
SEE ALSO
intuition.libraryActivateWindow(), intuition.libraryWindowToFront()
intuition.libraryZipWindow(), intuition.libraryScreenToFront()
matrix.library/MX_SortList matrix.library/MX_SortList
NAME
MX_SortList -- sort a linked list. (V22)
SYNOPSIS
MX_SortList(list)
a0
APTR list;
FUNCTION
Sorts a linked list into prioritized alphbetic order.
INPUTS
list = pointer to linked list to sort.
RESULT
None.
NOTES
Make sure the LN_PRI field of each node is set, if you do
not want a prioritized sort then set this to zero for all nodes.
This function call MX_NewSortList().
SEE ALSO
MX_NewSortList(),MX_AddNodeSorted(), MX_TextFileToList(),
MX_FreeListNodes(), MX_FreeList()
matrix.library/MX_SoundID matrix.library/MX_SoundID
NAME
MX_SoundID -- play a sound ID through MSD. (V23)
SYNOPSIS
result = MX_SoundID(basename,name)
d0 a0 a1
STRPTR basename;
STRPTR name;
FUNCTION
Plays a sound ID through matrix sound daemon (MSD).
INPUTS
basename - pointer to string to be used as a base path for the
sample id. This may be NULL but it is suggested that
a basename be used to identify the program requesting the
sample. Eg. "myprogram"
name - this is the specific sample ID to be played. If this is
not provided then the name used is "Beep".
RESULT
Returns FALSE if unable to locate the MSD message port.
NOTES
The soundID name is built up from the basename and the name similar
to DOS paths. Examples:
"myprogram","TheSound" --> "myprogram/TheSound"
"myprogram/general","Warning" --> "myprogram/general/Warning"
SEE ALSO
matrix.library/MX_StrCpyLen matrix.library/MX_StrCpyLen
NAME
MX_StrCpyLen -- copy string up to specified max length (V22)
SYNOPSIS
MX_StrCpyLen(source,dest,size)
a0 a1 d0
STRPTR source;
STRPTR dest;
LONG size;
FUNCTION
Copy a string into a buffer of specified length.
INPUTS
source = pointer to a null terminated string.
dest = pointer to a buffer to copy string into.
size = maximum number of characters to copy.
RESULT
None.
NOTES
The destination buffer MUST be of size+1 bytes long, this is
because the string is padded with a NULL byte.
SEE ALSO
MX_StrLen()
matrix.library/MX_StrCpyWord matrix.library/MX_StrCpyWord
NAME
MX_StrCpyWord -- copy the next word from source string (V23)
SYNOPSIS
next = MX_StrCpyWord(source,dest)
d0 a0 a1
STRPTR next;
STRPTR source;
STRPTR dest;
FUNCTION
Copy a the next word from the source buffer into the
destination buffer. If there are no more words or the
source pointer is NULL then NULL will be returned.
INPUTS
source = pointer to a null terminated string or NULL.
dest = pointer to a buffer to copy string into.
RESULT
next = pointer to the start of the next word in the source
buffer, or NULL if the end of string marker was reached.
NOTES
The destination buffer MUST be large enough to copy the word into.
matrix.library/MX_StrLen matrix.library/MX_StrLen
NAME
MX_StrLen -- get the length of a string (V22)
SYNOPSIS
length MX_StrLen(string)
d0 a0
LONG length;
STRPTR string;
FUNCTION
Compute the length of a null terminated string.
INPUTS
string = pointer to a null terminated string.
RESULT
length = the number of characters in the string, excluding the
null terminating byte.
NOTES
Register a0 (string pointer) is returned unchanged, other scratch
registers are modified (a1,d1).
SEE ALSO
MX_StrCpyLen
matrix.library/MX_TaskName matrix.library/MX_TaskName
NAME
MX_TaskName -- get the "real" name of our task.
SYNOPSIS
success = MX_TaskName(buffer,task,tags,size)
d0 a0 a1 a2 d0
LONG success;
STRPTR buffer;
struct Task *task;
struct TagItem *tags;
LONG size;
FUNCTION
Fills a buffer with the name or full pathname of the specified
task.
INPUTS
buffer = pointer to buffer to store the name/pathname.
task = pointer to task or NULL. If NULL is used then the
current task will be used unless overidden by the tag
MXTN_TaskPtr or MXTN_TaskName.
tags = pointer to a tag list or NULL.
size = length of buffer in bytes. May not be ZERO.
RESULT
success = TRUE if successful, FALSE otherwise.
TAGS
MXTN_TaskPtr (struct Task *) - pointer to task, overides task
parameter.
MXTN_TaskName (UBYTE *) - pointer to name of task. Only really of
use if used with MXTN_FullPath. Overides task parameter.
MXTN_FullPath (BOOLEAN) - if TRUE then the full path name of the
specified task will be given. If FALSE then only the name of
the task will be given. Defaults to TRUE.
SEE ALSO
exec.library/FindTask()
matrix.library/MX_TextFileToList matrix.library/MX_TextFileToList
NAME
MX_TextFileToList -- create a linked list from a text file. (V22)
SYNOPSIS
result = MX_TextFileToList(head,filename,tags)
d0 a0 a1 a2
LONG result;
APTR head;
STRPTR filename;
struct TagItem *tags;
FUNCTION
Creates a linked list from a text file.
INPUTS
head = pointer to a listhead that is initialized. If
there are any entries in the list they are freed
using MX_FreeListNodes().
filename = pointer to a filename to read.
tags = pointer to a tag list. Please keep this NULL.
RESULT
result = count of number of lines added to the listview,
or -1 on failure.
TAGS
MXTFL_AllocateFullLine (BOOLEAN) = should the allocated
buffer be allocated to MXTFL_LineLength. This may
not be used with a MXTFL_LineLength of -1. Default
is FALSE. (V24)
MXTFL_AllocateLNNAME (BOOLEAN) = if set to TRUE then
the ln_Name field is allocated to the length of
the line. When you free the list you *MUST* also
free the ln_Name field using FreeVec().
MXTFL_AllocateStrings (BOOLEAN) = if set to FALSE then
LN_NAME string pointers are not allocated and point
to the source buffer. The source buffer will be
modified after, having linefeeds converted to NULL
bytes. You may not use the following tags in
conjunction with this tag:
MXTFL_FileHandle, MXTFL_LeadingSpaces,
MXTFL_LineLength, MXTFL_SplitLines,
MXTFL_AllocateFullLine.
You must specify the buffer using MXTFL_SourceBuffer,
but please note that this buffer may not be reused
in this routine as the end of buffer NULL character
will be encountered on the first line.
Default = TRUE. (V24)
MXTFL_FileHandle (APTR) = filehandle of file to read,
this will be used instead of the filename passed in.
NOTE: This filehandle will be closed when finished.
(V23)
MXTFL_LeadingSpaces (ULONG) = number of leading spaces.
NOTE: This reduces the MXTFL_LineLength value so
make sure it is less tha this. Default = 0. (V23)
MXTFL_LineLength (ULONG) = maximum length for a line of
text. The default length is 80 characters. Must be
greater than 0. (V23)
If -1 then the full line will be used.
MXTFL_MemAttr (ULONG) = attributes for the memory
allocations. Default = 0. (V24)
MXTFL_NodeSize (ULONG) = size of list node entry, this
defaults to LN_SIZEOF. Must be greater or equal
to LN_SIZEOF. (V23)
Note: The LN_TYPE and LN_PRI fields are initialized
to zero always.
MXTFL_SourceBuffer (APTR) = pointer to a text buffer.
This will be used instead of the filename passed
in. The buffer *MUST* be null terminated. (V23)
MXTFL_SplitLines (BOOLEAN) = set to TRUE if you want
lines longer than the buffer to be spread over
several lines. Deafult = FALSE. Not implemented.
(V23)
NOTES
The list entries allocated by this function may be
deallocated by a call to MX_FreeListNodes().
SEE ALSO
MX_FreeListNodes(), MX_FreeList()
matrix.library/MX_TimeString matrix.library/MX_TimeString
NAME
MX_TimeString -- OBSOLETE
SYNTAX
MX_TimeString(buffer,seconds,type)
a0 d0 d1
NOTES
dos.library and locale.library provide satisfactory
system routines for this.
matrix.library/MX_UnlockMxBase matrix.library/MX_UnlockMxBase
NAME
MX_UnlockMxBase -- Surrender lock on MxBase by MX_LockMxBase(). (V23)
SYNOPSIS
MX_UnlockMxBase()
NOTE
This call is guaranteed to preserve all registers.
SEE ALSO
MX_LockMxBase()
matrix.library/MX_UnlockWindow matrix.library/MX_UnlockWindow
NAME
MX_UnlockWindow -- enable a window. (V21)
SYNOPSIS
MX_UnlockWindow(window,lock)
a0 a1
struct Window *window;
APTR lock;
FUNCTION
Enable the gadgets and restore mouse pointer.
INPUTS
window - pointer to window to be unlocked.
lock - the lock returned by MX_LockWindow() or NULL.
RESULT
None.
SEE ALSO
MX_LockWindow()
matrix.library/MX_UpdateVBLankInterrupt matrix.library/MX_UpdateVBLankInterrupt
NAME
MX_UpdateVBLankInterrupt -- install remove the vblank interrupt (V23)
SYNOPSIS
state = MX_UpdateVBLankInterrupt()
ULONG state;
FUNCTION
If the VBLANK list is empty and the interrupt is installed then
the interrupt will be removed. If the list is not empty and the
interrupt is not installed then it will be. This function is for
private use by matrix.library.
RESULT
state = (0) if interrupt is not running, or (1) if the interrupt
is running.
NOTES
This function is private for use by matrix.library only.
SEE ALSO
MX_AddVBlankNode(), MX_RemVBlankNode()
matrix.library/MX_WhereAmI matrix.library/MX_WhereAmI
NAME
MX_WhereAmI -- OBSOLETE FUNCTION
SYNOPSIS
formhandle = MX_OpenFormReq(hail,path,file,type,mode,tags)
d0 a0 a1 a2 a3 d0 d1
matrix.library/MX_WindowHandler matrix.library/MX_WindowHandler
NAME
MX_WindowHandler -- do some windowy stuff
SYNOPSIS
result = MX_WindowHandler(window,[screen],tags,vi)
d0 a0 [a1] d0 d1
ULONG result;
struct Window *window;
struct Screen *screen;
struct TagItem *tags;
struct VisInfo *vi;
FUNCTION
Does lots of windowy stuff
INPUTS
window =
screen =
tags =
vi =
RESULT
Returns FALSE if error occurs otherwise it is the value
wh_ReturnVal set in the wh structure.
TAGS
MXWH_ASLInfo (APTR) = Pointer to matrix asl info structure,
this consists of positional information for asl requestors
associated with this window.
MXWH_Catalog (APTR) = pointere to open catalog as returned by
locale.library/OpenCatalogA() (V24)
MXWH_CatalogName (STRPTR) = name of catalog file to load. (V24)
MXWH_CatCompArray (APTR) = pointer to array of ID,STRPTRS.
When specifying the labels for gadgets, you provide the
string id for lookup using locale.library. (V24)
MXWH_CloseWindow (ULONG) = wh_ReturnVal when the close gadget
is selected. Default = ~0 = no close gadget.
MXWH_ESCAddress (APTR) = Pointer to user function that is
called when the ESC key is pressed. If Set to ~0 the active
byte in the wh structure is cleared MXWH_ESCvalue tag data
value is set in wh_ReturnVal. The user function is called as
follows:
void Function(wh)
a0
MXWH_ESCvalue (ULONG) = wh_ReturnVal when the ESC key is
pressed. Default = 0. MXWH_ESCAddress must also be set.
MXWH_Events (APTR) = Pointer to array of longword pairs,
terminated by a NULL longword. This array consists
of IDCMP Code and Function pairs.
used = Function(wh,intuiMsg)
d0 a0 a1
The function should return TRUE if it used the message
and does not want matrix.library to process it.
You may also need to set the tag MXWH_IDCMPFlags.
(V23.1032) It is no longer necessary to specify the
tag MXWH_IDCMPFlags as matrix calculates what the
mask is from the events you are requesting.
MXWH_Gadgets (APTR) = Pointer to matrix gadget data to be
passed to MX_CreateGadgets().
MXWH_Handler (APTR) =
MXWH_IDCMPFlags (ULONG) = Mask of IDCMP flags to be
recieved. Use this in conjunction with MXWH_Events.
MXWH_InitCode (APTR) = Pointer to function called after the
window has been opened. You should you this to set up
any graphics you wish to render into the window.
void Function(wh)
a0
MXWH_Locale (APTR) = pointer to open locale as returned by
locale.library/OpenLocale() (V24)
MXWH_LocaleName (STRPTR) = pointer to locale name or NULL for
the default locale. (V24)
MXWH_Menus (APTR) = Pointer to menu array to be passed to
CreateMenusA() and LayoutMenusA(). If not specified then
the window will not have any menus and RMBTRAP will be
set in the window flags. This array is localized.
MXWH_MenusLocalize (BOOLEAN) = set to FALSE if you do not want
the menustrip to be localized. Default = TRUE.
MXWH_NoDepth (BOOLEAN) = Set to TRUE and the depth gadget will
not be added to the window. Default = FALSE.
MXWH_NoDrag (BOOLEAN) = Set to TRUE to disable the dragbar of
the window. Default = FALSE.
MXWH_Position (APTR) = Pointer to two WORDs that contain the
windows desired position. These will be updated when
the window is closed. Set either X or Y position to -1
and the window will be centered.
MXWH_PositionInWindow (BOOLEAN) = if set to true then the
when the window is opened, instead of centering it will
open with its top left corner just inside the parent
windows top left borders. It is necessary to specify
a parent window. The MXWH_Position tag will overide
this tag unless it is set to -1. (V23)
Not this tag has been renamed MXWH_PositionWindow and
is no longer a boolean
MXWH_PositionWindow (ULONG) = method for positioning the
window. See also MXWH_PositionInWindow
MXWH_RemakeWindowHook (APTR) = Hook function to call when
the window graphics need to be redrawn. (V23)
void Function(wh,intuiMsg)
a0 a1
MXWH_ScreenTitle (STRPTR) = pointer to the screen title to
be displayed when the window is active. (V23)
MXWH_Signals (ULONG) = Mask of signals to be processed by
the MXWH_SignalHandler tag function.
MXWH_SignalHandler (APTR) = Pointer to function to process
the signals specified in the MXWH_Signals tags mask.
void Function(wh,sigmaskRecievd)
a0 d0
MXWH_UseParentPort (BOOLEAN) = Set to TRUE if you wish this
window to share the parent window's message port. It is
important for this to be TRUE if the parent window has
additional graphics rendered into the window, such as
the boxes/borders drawn by matrix.library. Also any
custom rendering will have to be taken care of with a
user callback through MXWH_RemakeWindowHook
Default = TRUE. (V23)
MXWH_UserData (ULONG) = User data set in the window handler
structure which is passed to callback functions. The
userdata field is wh_UserData.
MXWH_VisualInfo (APTR) =
MXWH_WindowPointer (APTR) = Pointer to a longword which is
to cantain a pointer to the window. This is set to its
original value when the window is closed.
MXWH_WindowSize (ULONG) = This specifies the width AND the
height of the window in characters, with the width
given as a word in bits 16-31 and the height in bits
0-15. (V23) Default = NONE. This MUST be specified.
MXWH_WindowTitle (STRPTR) = Pointer to the title to be
used for the window.
MXWH_WindowTitleMSGID (ULONG) = this is the stringNum that
is passed to MX_GetCatalogStr() (V24)
(many more)
SEE ALSO
MX_WindowHandler2(), MX_CreateGadgets(), MX_GetCatalogStr()
matrix.library/MX_WrapText matrix.library/MX_WrapText
NAME
MX_WrapText -- remove the last word of a line
SYNOPSIS
MX_WrapText(source,dest)
a0 a1
APTR source;
APTR dest;
FUNCTION
INPUTS
source =
dest =
RESULT
None
NOTE
BUGS
SEE ALSO
MX_JustifyText()
matrix.library/MX_WriteForm matrix.library/MX_WriteForm
NAME
MX_WriteForm -- OBSOLETE FUNCTION
SYNOPSIS
MX_WriteForm(formhandle,buffer,size,type)
a0 a1 d0 d1
matrix.library/MX_WriteFormTagList matrix.library/MX_WriteFormTagList
NAME
MX_WriteFormTagList -- OBSOLETE FUNCTION
SYNOPSIS
MX_WriteFormTagList(formhandle,buffer,size,tags,type)
a0 a1 d0 d1 d2